<!DOCTYPE html>

<html lang="en" data-content_root="../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <title>cmake-instrumentation(7) &mdash; CMake 4.1.1 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=a2c47e09" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css?v=4d06bd55" />
    
    <script src="../_static/documentation_options.js?v=e6a937a4"></script>
    <script src="../_static/doctools.js?v=9bcbadda"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="cmake-language(7)" href="cmake-language.7.html" />
    <link rel="prev" title="Sublime Text 2" href="../generator/Sublime%20Text%202.html" />
 

  </head><body>
    <input id="sidebar-check" type="checkbox" />
    <label id="sidebar-overlay" for="sidebar-check"></label>



    <div class="related relbar1" role="navigation" aria-label="Related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="cmake-language.7.html" title="cmake-language(7)"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="../generator/Sublime%20Text%202.html" title="Sublime Text 2"
             accesskey="P">previous</a> |</li>
  <li>
    <label class="sidebar-toggle" for="sidebar-check"></label>
  </li>
  <li class="rootlink">
    <img src="../_static/cmake-logo-16.png" width="16" height="16" alt=""/>
    <a href="https://cmake.org/">CMake 4.1.1</a>
    <span class="reldelim1"> &#187;</span>
  </li>
  <li>
    <a href="../index.html">Documentation</a> &#187;
  </li>

        <li class="nav-item nav-item-this"><a href="">cmake-instrumentation(7)</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <span class="target" id="manual:cmake-instrumentation(7)"></span><section id="cmake-instrumentation-7">
<h1><a class="toc-backref" href="#id1" role="doc-backlink">cmake-instrumentation(7)</a><a class="headerlink" href="#cmake-instrumentation-7" title="Link to this heading">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 4.0.</span></p>
</div>
<nav class="contents" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#cmake-instrumentation-7" id="id1">cmake-instrumentation(7)</a></p>
<ul>
<li><p><a class="reference internal" href="#introduction" id="id2">Introduction</a></p>
<ul>
<li><p><a class="reference internal" href="#data-collection" id="id3">Data Collection</a></p></li>
<li><p><a class="reference internal" href="#indexing" id="id4">Indexing</a></p></li>
<li><p><a class="reference internal" href="#callbacks" id="id5">Callbacks</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#enabling-instrumentation" id="id6">Enabling Instrumentation</a></p>
<ul>
<li><p><a class="reference internal" href="#enabling-instrumentation-at-the-project-level" id="id7">Enabling Instrumentation at the Project-Level</a></p></li>
<li><p><a class="reference internal" href="#enabling-instrumentation-at-the-user-level" id="id8">Enabling Instrumentation at the User-Level</a></p></li>
<li><p><a class="reference internal" href="#enabling-instrumentation-for-cdash-submissions" id="id9">Enabling Instrumentation for CDash Submissions</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#api-v1" id="id10">API v1</a></p>
<ul>
<li><p><a class="reference internal" href="#v1-query-files" id="id11">v1 Query Files</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#data-v1" id="id12">Data v1</a></p>
<ul>
<li><p><a class="reference internal" href="#v1-snippet-file" id="id13">v1 Snippet File</a></p></li>
<li><p><a class="reference internal" href="#v1-index-file" id="id14">v1 Index File</a></p></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
<section id="introduction">
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Introduction</a><a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This feature is only available when experimental support for instrumentation
has been enabled by the <code class="docutils literal notranslate"><span class="pre">CMAKE_EXPERIMENTAL_INSTRUMENTATION</span></code> gate.</p>
</div>
<p>The CMake Instrumentation API allows for the collection of timing data, target
information and system diagnostic information during the configure, generate,
build, test and install steps for a CMake project.</p>
<p>This feature is only available for projects using the <a class="reference internal" href="cmake-generators.7.html#makefile-generators"><span class="std std-ref">Makefile Generators</span></a>
or the <a class="reference internal" href="cmake-generators.7.html#ninja-generators"><span class="std std-ref">Ninja Generators</span></a>.</p>
<p>All interactions with the CMake instrumentation API must specify both an API
version and a Data version. At this time, there is only one version for each of
these: the <a class="reference internal" href="#api-v1">API v1</a> and <a class="reference internal" href="#data-v1">Data v1</a>.</p>
<section id="data-collection">
<h3><a class="toc-backref" href="#id3" role="doc-backlink">Data Collection</a><a class="headerlink" href="#data-collection" title="Link to this heading">¶</a></h3>
<p>Whenever a command is executed with
instrumentation enabled, a <a class="reference internal" href="#v1-snippet-file">v1 Snippet File</a> is created in the project build
tree with data specific to that command. These files remain until after
<a class="reference internal" href="#indexing">Indexing</a> occurs.</p>
<p>CMake sets the <span class="target" id="index-0-prop_gbl:RULE_LAUNCH_COMPILE"></span><a class="reference internal" href="../prop_gbl/RULE_LAUNCH_COMPILE.html#prop_gbl:RULE_LAUNCH_COMPILE" title="RULE_LAUNCH_COMPILE"><code class="xref cmake cmake-prop_gbl docutils literal notranslate"><span class="pre">RULE_LAUNCH_COMPILE</span></code></a>, <span class="target" id="index-0-prop_gbl:RULE_LAUNCH_LINK"></span><a class="reference internal" href="../prop_gbl/RULE_LAUNCH_LINK.html#prop_gbl:RULE_LAUNCH_LINK" title="RULE_LAUNCH_LINK"><code class="xref cmake cmake-prop_gbl docutils literal notranslate"><span class="pre">RULE_LAUNCH_LINK</span></code></a> and
<span class="target" id="index-0-prop_gbl:RULE_LAUNCH_CUSTOM"></span><a class="reference internal" href="../prop_gbl/RULE_LAUNCH_CUSTOM.html#prop_gbl:RULE_LAUNCH_CUSTOM" title="RULE_LAUNCH_CUSTOM"><code class="xref cmake cmake-prop_gbl docutils literal notranslate"><span class="pre">RULE_LAUNCH_CUSTOM</span></code></a> global properties to use the
<code class="docutils literal notranslate"><span class="pre">ctest</span> <span class="pre">--instrument</span></code> launcher in order to capture details of each compile, link
and custom command respectively. If the project has been configured with <span class="target" id="index-0-module:CTestUseLaunchers"></span><a class="reference internal" href="../module/CTestUseLaunchers.html#module:CTestUseLaunchers" title="CTestUseLaunchers"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">CTestUseLaunchers</span></code></a>,
<code class="docutils literal notranslate"><span class="pre">ctest</span> <span class="pre">--instrument</span></code> will also include the behavior usually performed by
<code class="docutils literal notranslate"><span class="pre">ctest</span> <span class="pre">--launch</span></code>.</p>
</section>
<section id="indexing">
<h3><a class="toc-backref" href="#id4" role="doc-backlink">Indexing</a><a class="headerlink" href="#indexing" title="Link to this heading">¶</a></h3>
<p>Indexing is the process of collating generated instrumentation data. Indexing
occurs at specific intervals called hooks, such as after every build. These
hooks are configured as part of the <a class="reference internal" href="#v1-query-files">v1 Query Files</a>. Whenever a hook is
triggered, an index file is generated containing a list of snippet files newer
than the previous indexing.</p>
<p>Indexing and can also be performed by manually invoking
<code class="docutils literal notranslate"><span class="pre">ctest</span> <span class="pre">--collect-instrumentation</span> <span class="pre">&lt;build&gt;</span></code>.</p>
</section>
<section id="callbacks">
<h3><a class="toc-backref" href="#id5" role="doc-backlink">Callbacks</a><a class="headerlink" href="#callbacks" title="Link to this heading">¶</a></h3>
<p>As part of the <a class="reference internal" href="#v1-query-files">v1 Query Files</a>, users can provide a list of callbacks
intended to handle data collected by this feature.</p>
<p>Whenever <a class="reference internal" href="#indexing">Indexing</a> occurs, each provided callback is executed, passing the
path to the generated index file as an argument.</p>
<p>These callbacks, defined either at the user-level or project-level should read
the instrumentation data and perform any desired handling of it. The index file
and its listed snippets are automatically deleted by CMake once all callbacks
have completed. Note that a callback should never move or delete these data
files manually as they may be needed by other callbacks.</p>
</section>
</section>
<section id="enabling-instrumentation">
<h2><a class="toc-backref" href="#id6" role="doc-backlink">Enabling Instrumentation</a><a class="headerlink" href="#enabling-instrumentation" title="Link to this heading">¶</a></h2>
<p>Instrumentation can be enabled either for an individual CMake project, or
for all CMake projects configured and built by a user. For both cases,
see the <a class="reference internal" href="#v1-query-files">v1 Query Files</a> for details on configuring this feature.</p>
<section id="enabling-instrumentation-at-the-project-level">
<h3><a class="toc-backref" href="#id7" role="doc-backlink">Enabling Instrumentation at the Project-Level</a><a class="headerlink" href="#enabling-instrumentation-at-the-project-level" title="Link to this heading">¶</a></h3>
<p>Project code can contain instrumentation queries with the
<span class="target" id="index-0-command:cmake_instrumentation"></span><a class="reference internal" href="../command/cmake_instrumentation.html#command:cmake_instrumentation" title="cmake_instrumentation"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">cmake_instrumentation()</span></code></a> command.</p>
<p>In addition, query files can be placed manually under
<code class="docutils literal notranslate"><span class="pre">&lt;build&gt;/.cmake/instrumentation/&lt;version&gt;/query/</span></code> at the top of a build tree.
This version of CMake supports only one version schema, <a class="reference internal" href="#api-v1">API v1</a>.</p>
</section>
<section id="enabling-instrumentation-at-the-user-level">
<h3><a class="toc-backref" href="#id8" role="doc-backlink">Enabling Instrumentation at the User-Level</a><a class="headerlink" href="#enabling-instrumentation-at-the-user-level" title="Link to this heading">¶</a></h3>
<p>Instrumentation can be configured at the user-level by placing query files in
the <span class="target" id="index-0-envvar:CMAKE_CONFIG_DIR"></span><a class="reference internal" href="../envvar/CMAKE_CONFIG_DIR.html#envvar:CMAKE_CONFIG_DIR" title="CMAKE_CONFIG_DIR"><code class="xref cmake cmake-envvar docutils literal notranslate"><span class="pre">CMAKE_CONFIG_DIR</span></code></a> under
<code class="docutils literal notranslate"><span class="pre">&lt;config_dir&gt;/instrumentation/&lt;version&gt;/query/</span></code>.</p>
</section>
<section id="enabling-instrumentation-for-cdash-submissions">
<h3><a class="toc-backref" href="#id9" role="doc-backlink">Enabling Instrumentation for CDash Submissions</a><a class="headerlink" href="#enabling-instrumentation-for-cdash-submissions" title="Link to this heading">¶</a></h3>
<p>You can enable instrumentation when using CTest in <a class="reference internal" href="ctest.1.html#dashboard-client"><span class="std std-ref">Dashboard Client</span></a>
mode by setting the <span class="target" id="index-0-envvar:CTEST_USE_INSTRUMENTATION"></span><a class="reference internal" href="../envvar/CTEST_USE_INSTRUMENTATION.html#envvar:CTEST_USE_INSTRUMENTATION" title="CTEST_USE_INSTRUMENTATION"><code class="xref cmake cmake-envvar docutils literal notranslate"><span class="pre">CTEST_USE_INSTRUMENTATION</span></code></a> environment variable
to the current UUID for the <code class="docutils literal notranslate"><span class="pre">CMAKE_EXPERIMENTAL_INSTRUMENTATION</span></code> feature.
Doing so automatically enables the <code class="docutils literal notranslate"><span class="pre">dynamicSystemInformation</span></code> query.</p>
<p>The following table shows how each type of instrumented command gets mapped
to a corresponding type of CTest XML file.</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p><a class="reference internal" href="#cmake-instrumentation-data-v1"><span class="std std-ref">Snippet Role</span></a></p></th>
<th class="head"><p>CTest XML File</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">configure</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Configure.xml</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">generate</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Configure.xml</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">compile</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Build.xml</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">link</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Build.xml</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">custom</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Build.xml</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">build</span></code></p></td>
<td><p>unused!</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">cmakeBuild</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Build.xml</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">cmakeInstall</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Build.xml</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">install</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Build.xml</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ctest</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Build.xml</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">test</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Test.xml</span></code></p></td>
</tr>
</tbody>
</table>
<p>By default the command line reported to CDash is truncated at the first space.
You can instead choose to report the full command line (including arguments)
by setting <span class="target" id="index-0-envvar:CTEST_USE_VERBOSE_INSTRUMENTATION"></span><a class="reference internal" href="../envvar/CTEST_USE_VERBOSE_INSTRUMENTATION.html#envvar:CTEST_USE_VERBOSE_INSTRUMENTATION" title="CTEST_USE_VERBOSE_INSTRUMENTATION"><code class="xref cmake cmake-envvar docutils literal notranslate"><span class="pre">CTEST_USE_VERBOSE_INSTRUMENTATION</span></code></a> to 1.</p>
</section>
</section>
<section id="api-v1">
<span id="cmake-instrumentation-api-v1"></span><h2><a class="toc-backref" href="#id10" role="doc-backlink">API v1</a><a class="headerlink" href="#api-v1" title="Link to this heading">¶</a></h2>
<p>The API version specifies both the subdirectory layout of the instrumentation data,
and the format of the query files.</p>
<p>The Instrumentation API v1 is housed  in the <code class="docutils literal notranslate"><span class="pre">instrumentation/v1/</span></code> directory
under either <code class="docutils literal notranslate"><span class="pre">&lt;build&gt;/.cmake/</span></code> for output data and project-level queries, or
<code class="docutils literal notranslate"><span class="pre">&lt;config_dir&gt;/</span></code> for user-level queries. The <code class="docutils literal notranslate"><span class="pre">v1</span></code> component of this
directory is what signifies the API version. It has the following
subdirectories:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">query/</span></code></dt><dd><p>Holds query files written by users or clients. Any file with the <code class="docutils literal notranslate"><span class="pre">.json</span></code>
file extension will be recognized as a query file. These files are owned by
whichever client or user creates them.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">query/generated/</span></code></dt><dd><p>Holds query files generated by a CMake project with the
<span class="target" id="index-1-command:cmake_instrumentation"></span><a class="reference internal" href="../command/cmake_instrumentation.html#command:cmake_instrumentation" title="cmake_instrumentation"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">cmake_instrumentation()</span></code></a> command. These files are owned by CMake and
are deleted and regenerated automatically during the CMake configure step.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">data/</span></code></dt><dd><p>Holds instrumentation data collected on the project. CMake owns all data
files, they should never be removed by other processes. Data collected here
remains until after <a class="reference internal" href="#indexing">Indexing</a> occurs and all <a class="reference internal" href="#callbacks">Callbacks</a> are executed.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">cdash/</span></code></dt><dd><p>Holds temporary files used internally to generate XML content to be submitted
to CDash.</p>
</dd>
</dl>
<section id="v1-query-files">
<span id="cmake-instrumentation-v1-query-files"></span><h3><a class="toc-backref" href="#id11" role="doc-backlink">v1 Query Files</a><a class="headerlink" href="#v1-query-files" title="Link to this heading">¶</a></h3>
<p>Any file with the <code class="docutils literal notranslate"><span class="pre">.json</span></code> extension under the <code class="docutils literal notranslate"><span class="pre">instrumentation/v1/query/</span></code>
directory is recognized as a query for instrumentation data.</p>
<p>These files must contain a JSON object with the following keys. The <code class="docutils literal notranslate"><span class="pre">version</span></code>
key is required, but all other fields are optional.</p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">version</span></code></dt><dd><p>The Data version of snippet file to generate, an integer. Currently the only
supported version is <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">callbacks</span></code></dt><dd><p>A list of command-line strings for <a class="reference internal" href="#callbacks">Callbacks</a> to handle collected
instrumentation data. Whenever these callbacks are executed, the full path to
a <a class="reference internal" href="#v1-index-file">v1 Index File</a> is appended to the arguments included in the string.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">hooks</span></code></dt><dd><p>A list of strings specifying when <a class="reference internal" href="#indexing">Indexing</a> should occur automatically.
These are the intervals when instrumentation data should be collated and user
<a class="reference internal" href="#callbacks">Callbacks</a> should be invoked to handle the data. Elements in this list
should be one of the following:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">postGenerate</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">preBuild</span></code> (called when <code class="docutils literal notranslate"><span class="pre">ninja</span></code>  or <code class="docutils literal notranslate"><span class="pre">make</span></code> is invoked; unavailable on Windows)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">postBuild</span></code> (called when <code class="docutils literal notranslate"><span class="pre">ninja</span></code> or <code class="docutils literal notranslate"><span class="pre">make</span></code> completes; unavailable on Windows)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">preCMakeBuild</span></code> (called when <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span></code> is invoked)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">postCMakeBuild</span></code> (called when <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span></code> completes)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">postInstall</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">postTest</span></code></p></li>
</ul>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">queries</span></code></dt><dd><p>A list of strings specifying additional optional data to collect during
instrumentation. Elements in this list should be one of the following:</p>
<blockquote>
<div><dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">staticSystemInformation</span></code></dt><dd><p>Enables collection of the static information about the host machine CMake
is being run from. This data is collected during <a class="reference internal" href="#indexing">Indexing</a> and is
included in the generated <a class="reference internal" href="#v1-index-file">v1 Index File</a>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dynamicSystemInformation</span></code></dt><dd><p>Enables collection of the dynamic information about the host machine
CMake is being run from. Data is collected for every <a class="reference internal" href="#v1-snippet-file">v1 Snippet File</a>
generated by CMake, and includes information from immediately before and
after the command is executed.</p>
</dd>
</dl>
</div></blockquote>
</dd>
</dl>
<p>The <code class="docutils literal notranslate"><span class="pre">callbacks</span></code> listed will be invoked during the specified hooks
<em>at a minimum</em>. When there are multiple query files, the <code class="docutils literal notranslate"><span class="pre">callbacks</span></code>,
<code class="docutils literal notranslate"><span class="pre">hooks</span></code> and <code class="docutils literal notranslate"><span class="pre">queries</span></code> between them will be merged. Therefore, if any query
file includes any <code class="docutils literal notranslate"><span class="pre">hooks</span></code>, every <code class="docutils literal notranslate"><span class="pre">callback</span></code> across all query files will be
executed at every <code class="docutils literal notranslate"><span class="pre">hook</span></code> across all query files. Additionally, if any query
file includes any optional <code class="docutils literal notranslate"><span class="pre">queries</span></code>, the optional query data will be present
in all data files.</p>
<p>Example:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="w">  </span><span class="nt">&quot;version&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;callbacks&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
<span class="w">    </span><span class="s2">&quot;/usr/bin/python callback.py&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;/usr/bin/cmake -P callback.cmake arg&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="p">],</span>
<span class="w">  </span><span class="nt">&quot;hooks&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
<span class="w">    </span><span class="s2">&quot;postCMakeBuild&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;postInstall&quot;</span>
<span class="w">  </span><span class="p">],</span>
<span class="w">  </span><span class="nt">&quot;queries&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
<span class="w">    </span><span class="s2">&quot;staticSystemInformation&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;dynamicSystemInformation&quot;</span>
<span class="w">  </span><span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In this example, after every <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span></code> or <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--install</span></code>
invocation, an index file <code class="docutils literal notranslate"><span class="pre">index-&lt;timestamp&gt;.json</span></code> will be generated in
<code class="docutils literal notranslate"><span class="pre">&lt;build&gt;/.cmake/instrumentation/v1/data</span></code> containing a list of data snippet
files created since the previous indexing. The commands
<code class="docutils literal notranslate"><span class="pre">/usr/bin/python</span> <span class="pre">callback.py</span> <span class="pre">index-&lt;timestamp&gt;.json</span></code> and
<code class="docutils literal notranslate"><span class="pre">/usr/bin/cmake</span> <span class="pre">-P</span> <span class="pre">callback.cmake</span> <span class="pre">arg</span> <span class="pre">index-&lt;timestamp&gt;.json</span></code> will be executed in
that order. The index file will contain the <code class="docutils literal notranslate"><span class="pre">staticSystemInformation</span></code> data and
each snippet file listed in the index will contain the
<code class="docutils literal notranslate"><span class="pre">dynamicSystemInformation</span></code> data. Once both callbacks have completed, the index
file and all snippet files listed by it will be deleted from the project build
tree.</p>
</section>
</section>
<section id="data-v1">
<span id="cmake-instrumentation-data-v1"></span><h2><a class="toc-backref" href="#id12" role="doc-backlink">Data v1</a><a class="headerlink" href="#data-v1" title="Link to this heading">¶</a></h2>
<p>Data version specifies the contents of the output files generated by the CMake
instrumentation API as part of the <a class="reference internal" href="#data-collection">Data Collection</a> and <a class="reference internal" href="#indexing">Indexing</a>. There are
two types of data files generated: the <a class="reference internal" href="#v1-snippet-file">v1 Snippet File</a> and <a class="reference internal" href="#v1-index-file">v1 Index File</a>.
When using the <a class="reference internal" href="#api-v1">API v1</a>, these files live in
<code class="docutils literal notranslate"><span class="pre">&lt;build&gt;/.cmake/instrumentation/v1/data/</span></code> under the project build tree.</p>
<section id="v1-snippet-file">
<h3><a class="toc-backref" href="#id13" role="doc-backlink">v1 Snippet File</a><a class="headerlink" href="#v1-snippet-file" title="Link to this heading">¶</a></h3>
<p>Snippet files are generated for every compile, link and custom command invoked
as part of the CMake build or install step and contain instrumentation data about
the command executed. Additionally, snippet files are created for the following:</p>
<ul class="simple">
<li><p>The CMake configure step</p></li>
<li><p>The CMake generate step</p></li>
<li><p>Entire build step (executed with <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span></code>)</p></li>
<li><p>Entire install step (executed with <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--install</span></code>)</p></li>
<li><p>Each <code class="docutils literal notranslate"><span class="pre">ctest</span></code> invocation</p></li>
<li><p>Each individual test executed by <code class="docutils literal notranslate"><span class="pre">ctest</span></code>.</p></li>
</ul>
<p>These files remain in the build tree until after <a class="reference internal" href="#indexing">Indexing</a> occurs and any
user-specified <a class="reference internal" href="#callbacks">Callbacks</a> are executed.</p>
<p>Snippet files have a filename with the syntax <code class="docutils literal notranslate"><span class="pre">&lt;role&gt;-&lt;hash&gt;-&lt;timestamp&gt;.json</span></code>
and contain the following data:</p>
<blockquote>
<div><dl>
<dt><code class="docutils literal notranslate"><span class="pre">version</span></code></dt><dd><p>The Data version of the snippet file, an integer. Currently the version is
always <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">command</span></code></dt><dd><p>The full command executed. Excluded when <code class="docutils literal notranslate"><span class="pre">role</span></code> is <code class="docutils literal notranslate"><span class="pre">build</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">workingDir</span></code></dt><dd><p>The working directory in which the <code class="docutils literal notranslate"><span class="pre">command</span></code> was executed.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">result</span></code></dt><dd><p>The exit-value of the command, an integer.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">role</span></code></dt><dd><p>The type of command executed, which will be one of the following values:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">configure</span></code>: the CMake configure step</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">generate</span></code>: the CMake generate step</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">compile</span></code>: an individual compile step invoked during the build</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">link</span></code>: an individual link step invoked during the build</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">custom</span></code>: an individual custom command invoked during the build</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">build</span></code>: a complete <code class="docutils literal notranslate"><span class="pre">make</span></code> or <code class="docutils literal notranslate"><span class="pre">ninja</span></code> invocation. Only generated if <code class="docutils literal notranslate"><span class="pre">preBuild</span></code> or <code class="docutils literal notranslate"><span class="pre">postBuild</span></code> hooks are enabled.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cmakeBuild</span></code>: a complete <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span></code> invocation</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cmakeInstall</span></code>: a complete <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--install</span></code> invocation</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">install</span></code>: an individual <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">-P</span> <span class="pre">cmake_install.cmake</span></code> invocation</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ctest</span></code>: a complete <code class="docutils literal notranslate"><span class="pre">ctest</span></code> invocation</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">test</span></code>: a single test executed by CTest</p></li>
</ul>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">target</span></code></dt><dd><p>The CMake target associated with the command. Only included when <code class="docutils literal notranslate"><span class="pre">role</span></code> is
<code class="docutils literal notranslate"><span class="pre">compile</span></code> or <code class="docutils literal notranslate"><span class="pre">link</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">targetType</span></code></dt><dd><p>The <span class="target" id="index-0-prop_tgt:TYPE"></span><a class="reference internal" href="../prop_tgt/TYPE.html#prop_tgt:TYPE" title="TYPE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">TYPE</span></code></a> of the target. Only included when <code class="docutils literal notranslate"><span class="pre">role</span></code> is
<code class="docutils literal notranslate"><span class="pre">link</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">targetLabels</span></code></dt><dd><p>The <span class="target" id="index-0-prop_tgt:LABELS"></span><a class="reference internal" href="../prop_tgt/LABELS.html#prop_tgt:LABELS" title="LABELS"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">LABELS</span></code></a> of the target. Only included when <code class="docutils literal notranslate"><span class="pre">role</span></code> is
<code class="docutils literal notranslate"><span class="pre">link</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">timeStart</span></code></dt><dd><p>Time at which the command started, expressed as the number of milliseconds
since the system epoch.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">duration</span></code></dt><dd><p>The duration that the command ran for, expressed in milliseconds.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">outputs</span></code></dt><dd><p>The command's output file(s), an array. Only included when <code class="docutils literal notranslate"><span class="pre">role</span></code> is one
of: <code class="docutils literal notranslate"><span class="pre">compile</span></code>, <code class="docutils literal notranslate"><span class="pre">link</span></code>, <code class="docutils literal notranslate"><span class="pre">custom</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">outputSizes</span></code></dt><dd><p>The size(s) in bytes of the <code class="docutils literal notranslate"><span class="pre">outputs</span></code>, an array. For files which do not
exist, the size is 0. Included under the same conditions as the <code class="docutils literal notranslate"><span class="pre">outputs</span></code>
field.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">source</span></code></dt><dd><p>The source file being compiled. Only included when <code class="docutils literal notranslate"><span class="pre">role</span></code> is <code class="docutils literal notranslate"><span class="pre">compile</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">language</span></code></dt><dd><p>The language of the source file being compiled. Only included when <code class="docutils literal notranslate"><span class="pre">role</span></code> is
<code class="docutils literal notranslate"><span class="pre">compile</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">testName</span></code></dt><dd><p>The name of the test being executed. Only included when <code class="docutils literal notranslate"><span class="pre">role</span></code> is <code class="docutils literal notranslate"><span class="pre">test</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">config</span></code></dt><dd><p>The type of build, such as <code class="docutils literal notranslate"><span class="pre">Release</span></code> or <code class="docutils literal notranslate"><span class="pre">Debug</span></code>. Only included when
<code class="docutils literal notranslate"><span class="pre">role</span></code> is <code class="docutils literal notranslate"><span class="pre">compile</span></code>, <code class="docutils literal notranslate"><span class="pre">link</span></code> or <code class="docutils literal notranslate"><span class="pre">test</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dynamicSystemInformation</span></code></dt><dd><p>Specifies the dynamic information collected about the host machine
CMake is being run from. Data is collected for every snippet file
generated by CMake, with data immediately before and after the command is
executed. Only included when enabled by the <a class="reference internal" href="#v1-query-files">v1 Query Files</a>.</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">beforeHostMemoryUsed</span></code></dt><dd><p>The Host Memory Used in KiB at <code class="docutils literal notranslate"><span class="pre">timeStart</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">afterHostMemoryUsed</span></code></dt><dd><p>The Host Memory Used in KiB at <code class="docutils literal notranslate"><span class="pre">timeStop</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">beforeCPULoadAverage</span></code></dt><dd><p>The Average CPU Load at <code class="docutils literal notranslate"><span class="pre">timeStart</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">afterCPULoadAverage</span></code></dt><dd><p>The Average CPU Load at <code class="docutils literal notranslate"><span class="pre">timeStop</span></code>.</p>
</dd>
</dl>
</dd>
</dl>
</div></blockquote>
<p>Example:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="w">  </span><span class="nt">&quot;version&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;command&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;\&quot;/usr/bin/c++\&quot; \&quot;-MD\&quot; \&quot;-MT\&quot; \&quot;CMakeFiles/main.dir/main.cxx.o\&quot; \&quot;-MF\&quot; \&quot;CMakeFiles/main.dir/main.cxx.o.d\&quot; \&quot;-o\&quot; \&quot;CMakeFiles/main.dir/main.cxx.o\&quot; \&quot;-c\&quot; \&quot;&lt;src&gt;/main.cxx\&quot;&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;role&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;compile&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;return&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;target&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;main&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;language&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;C++&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;outputs&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">&quot;CMakeFiles/main.dir/main.cxx.o&quot;</span><span class="w"> </span><span class="p">],</span>
<span class="w">  </span><span class="nt">&quot;outputSizes&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="p">],</span>
<span class="w">  </span><span class="nt">&quot;source&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;&lt;src&gt;/main.cxx&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;config&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Debug&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;dynamicSystemInformation&quot;</span><span class="w"> </span><span class="p">:</span>
<span class="w">  </span><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;afterCPULoadAverage&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mf">2.3500000000000001</span><span class="p">,</span>
<span class="w">    </span><span class="nt">&quot;afterHostMemoryUsed&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mf">6635680.0</span>
<span class="w">    </span><span class="nt">&quot;beforeCPULoadAverage&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mf">2.3500000000000001</span><span class="p">,</span>
<span class="w">    </span><span class="nt">&quot;beforeHostMemoryUsed&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mf">6635832.0</span>
<span class="w">  </span><span class="p">},</span>
<span class="w">  </span><span class="nt">&quot;timeStart&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">1737053448177</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;duration&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">31</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="v1-index-file">
<h3><a class="toc-backref" href="#id14" role="doc-backlink">v1 Index File</a><a class="headerlink" href="#v1-index-file" title="Link to this heading">¶</a></h3>
<p>Index files contain a list of <a class="reference internal" href="#v1-snippet-file">v1 Snippet File</a>. It serves as an entry point
for navigating the instrumentation data. They are generated whenever <a class="reference internal" href="#indexing">Indexing</a>
occurs and deleted after any user-specified <a class="reference internal" href="#callbacks">Callbacks</a> are executed.</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">version</span></code></dt><dd><p>The Data version of the index file, an integer. Currently the version is
always <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">buildDir</span></code></dt><dd><p>The build directory of the CMake project.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dataDir</span></code></dt><dd><p>The full path to the <code class="docutils literal notranslate"><span class="pre">&lt;build&gt;/.cmake/instrumentation/v1/data/</span></code> directory.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">hook</span></code></dt><dd><p>The name of the hook responsible for generating the index file. In addition
to the hooks that can be specified by one of the <a class="reference internal" href="#v1-query-files">v1 Query Files</a>, this value may
be set to <code class="docutils literal notranslate"><span class="pre">manual</span></code> if indexing is performed by invoking
<code class="docutils literal notranslate"><span class="pre">ctest</span> <span class="pre">--collect-instrumentation</span> <span class="pre">&lt;build&gt;</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">snippets</span></code></dt><dd><p>Contains a list of <a class="reference internal" href="#v1-snippet-file">v1 Snippet File</a>. This includes all snippet files
generated since the previous index file was created. The file paths are
relative to <code class="docutils literal notranslate"><span class="pre">dataDir</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">staticSystemInformation</span></code></dt><dd><p>Specifies the static information collected about the host machine
CMake is being run from. Only included when enabled by the <a class="reference internal" href="#v1-query-files">v1 Query Files</a>.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">OSName</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">OSPlatform</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">OSRelease</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">OSVersion</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">familyId</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">hostname</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">is64Bits</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">modelId</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">numberOfLogicalCPU</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">numberOfPhysicalCPU</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">processorAPICID</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">processorCacheSize</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">processorClockFrequency</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">processorName</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">totalPhysicalMemory</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">totalVirtualMemory</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">vendorID</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">vendorString</span></code></p></li>
</ul>
</dd>
</dl>
<p>Example:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="w">  </span><span class="nt">&quot;version&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;hook&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;manual&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;buildDir&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;&lt;build&gt;&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;dataDir&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;&lt;build&gt;/.cmake/instrumentation/v1/data&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="nt">&quot;snippets&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
<span class="w">    </span><span class="s2">&quot;configure-&lt;hash&gt;-&lt;timestamp&gt;.json&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;generate-&lt;hash&gt;-&lt;timestamp&gt;.json&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;compile-&lt;hash&gt;-&lt;timestamp&gt;.json&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;compile-&lt;hash&gt;-&lt;timestamp&gt;.json&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;link-&lt;hash&gt;-&lt;timestamp&gt;.json&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;install-&lt;hash&gt;-&lt;timestamp&gt;.json&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;ctest-&lt;hash&gt;-&lt;timestamp&gt;.json&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;test-&lt;hash&gt;-&lt;timestamp&gt;.json&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="s2">&quot;test-&lt;hash&gt;-&lt;timestamp&gt;.json&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3>Table of Contents</h3>
    <ul>
<li><a class="reference internal" href="#">cmake-instrumentation(7)</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a><ul>
<li><a class="reference internal" href="#data-collection">Data Collection</a></li>
<li><a class="reference internal" href="#indexing">Indexing</a></li>
<li><a class="reference internal" href="#callbacks">Callbacks</a></li>
</ul>
</li>
<li><a class="reference internal" href="#enabling-instrumentation">Enabling Instrumentation</a><ul>
<li><a class="reference internal" href="#enabling-instrumentation-at-the-project-level">Enabling Instrumentation at the Project-Level</a></li>
<li><a class="reference internal" href="#enabling-instrumentation-at-the-user-level">Enabling Instrumentation at the User-Level</a></li>
<li><a class="reference internal" href="#enabling-instrumentation-for-cdash-submissions">Enabling Instrumentation for CDash Submissions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#api-v1">API v1</a><ul>
<li><a class="reference internal" href="#v1-query-files">v1 Query Files</a></li>
</ul>
</li>
<li><a class="reference internal" href="#data-v1">Data v1</a><ul>
<li><a class="reference internal" href="#v1-snippet-file">v1 Snippet File</a></li>
<li><a class="reference internal" href="#v1-index-file">v1 Index File</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  </div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="../generator/Sublime%20Text%202.html"
                          title="previous chapter">Sublime Text 2</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="cmake-language.7.html"
                          title="next chapter">cmake-language(7)</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/manual/cmake-instrumentation.7.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<search id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="Related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="cmake-language.7.html" title="cmake-language(7)"
             >next</a> |</li>
        <li class="right" >
          <a href="../generator/Sublime%20Text%202.html" title="Sublime Text 2"
             >previous</a> |</li>
  <li>
    <label class="sidebar-toggle" for="sidebar-check"></label>
  </li>
  <li class="rootlink">
    <img src="../_static/cmake-logo-16.png" width="16" height="16" alt=""/>
    <a href="https://cmake.org/">CMake 4.1.1</a>
    <span class="reldelim1"> &#187;</span>
  </li>
  <li>
    <a href="../index.html">Documentation</a> &#187;
  </li>

        <li class="nav-item nav-item-this"><a href="">cmake-instrumentation(7)</a></li> 
      </ul>
    </div>

    <div class="footer" role="contentinfo">
    &#169; Copyright 2000-2025 Kitware, Inc. and Contributors.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
    </div>
<script type="text/javascript">
(function() {
  "use strict";
  const hide = () => document.getElementById("sidebar-check").checked = false;
  addEventListener("keydown", e => (e.key === "Escape") && hide());
  addEventListener("click", e => (e.target.tagName === "A") && hide());
  addEventListener("hashchange", hide)
})();
</script>
  </body>
</html>